Skip to main content
POST
Handles `POST /v1/verify/face-match`.

Authorizations

Authorization
string
header
required

A tenant API key. Acts for exactly one tenant and cannot conclude a case, because a conclusion records a person.

Body

application/json

Face-match verification request body.

There is deliberately no tenant_id field. It used to be here, and the handler trusted it: any caller could name any tenant, and the route required no credentials at all, so biometrics could be submitted and evidence written against somebody else's account. The tenant now comes from the presented credentials like every other /v1 route, which is the only place it can come from and still mean anything.

candidate_image_base64
string
required

Base64-encoded candidate image (for example, a live selfie).

reference_image_base64
string
required

Base64-encoded reference image (for example, an ID document photo).

subject_id
string
required

Subject (platform user) being verified.

Response

A replayed Idempotency-Key; the original verification

Face-match verification response body.

decision
enum<string>
required

Decision outcome.

Available options:
ALLOW,
WARN,
BLOCK,
HOLD,
REVIEW_REQUIRED,
FLAG,
BLOCK_RECOMMENDED,
SUSPEND,
END_STREAM
decision_id
string
required

Decision record identifier.

evidence
object[]
required

References to retained evidence.

reasons
object[]
required

Explanation reasons.

review_status
enum<string>
required

Review lifecycle state.

Available options:
PENDING,
APPROVED,
OVERTURNED,
NOT_REQUIRED
risk_level
enum<string>
required

Explainable risk level.

Available options:
LOW,
MEDIUM,
HIGH,
CRITICAL
verification_id
string
required

Verification attempt identifier.

review_case_id
string | null

Manual-review case, when the decision is borderline.